This section outlines the functions specifically for use when targeting the UWP target platform. The initial set of functions are for controlling the general game behaviour when creating a UWP app:

• uwp_suspend
  
• uwp_is_suspending
  
• uwp_is_constrained
  
• uwp_was_terminated
  
• uwp_was_closed_by_user
  
• uwp_show_help
  
• uwp_license_trial_version
  
• uwp_license_trial_user
  
• uwp_license_trial_time_remaining
  
• uwp_check_privilege
  

UWP also permits you to create games for the XBox One platform using the XBox Live API using the following functions. These functions are require you to have checked the Enable XBox Live option in the UWP Game Options.

Some of these functions require the user to be signed-in to XBox Live, which GameMaker Studio 2 will try to do automatically when you run the project. This "silent" sign in will generate a System Asynchronous Event which can the be checked to see if it was successful or not before proceeding. Note that unlike the Xbox One Console export, the UWP export for XBox Live only permits one user to be signed-in at a time.

The following functions exist for you to use with XBox Live in your projects:

• xboxlive_user_is_signed_in
• xboxlive_user_is_signing_in
• xboxlive_gamertag_for_user
• xboxlive_show_account_picker

Users And Accounts

The Xbox One allows multiple users to sign in to a console simultaneously. Each user has a specific controller associated with them and any save game data is also user-specific. To make the most of this system, GameMaker Studio 2 introduces a number of XBox One only functions related to the association between controllers and users, permitting you to query information about the user and also controlling how save data is handled on a per-user basis. You can find further developer information about this system from the official white paper on the Microsoft developer site.

NOTE: Note that the User ID is unique to each individual and is perpetuated across different consoles, so if the same user signs in on two different devices this User ID will be the same.

The following functions exist for you to use with XBox Live accounts:

• xboxlive_get_user_count
  
• xboxlive_get_user
  
• xboxlive_get_activating_user
  
• xboxlive_user_is_guest
  
• xboxlive_user_is_signed_in
  
• xboxlive_user_is_signing_in
  
• xboxlive_user_is_active
  
• xboxlive_user_is_remote
• xboxlive_user_id_for_user
  
• xboxlive_sponsor_for_user
• xboxlive_set_rich_presence
  
• xboxlive_gamedisplayname_for_user
  
• xboxlive_user_for_pad
  
• xboxlive_pad_for_user
  
• xboxlive_pad_count_for_user
  
• xboxlive_show_account_picker
  
• xboxlive_agegroup_for_user
  
• xboxlive_gamerscore_for_user
  
• xboxlive_show_profile_card_for_user
  
• xboxlive_reputation_for_user
  
• xboxlive_sprite_add_from_gamerpicture
  
• xboxlive_gamertag_for_user
  
• xboxlive_generate_player_session_id
  

Save Data

The following functions are specifically to do with save data. While the save data related to player progress must always be associated with a particular user, you can save generic data to the "machine storage" area to by providing the value -1 as the user argument. This area is title-specific, but not associated with a particular user.

NOTE: No saved file can be larger than 16 megs!

The following functions are for dealing with Xbox Live save data:

• xboxlive_set_savedata_user
  
• xboxlive_get_savedata_user
  
• xboxlive_get_file_error
  

Stats

Xbox One Stats (achievements and leaderboards) are functional when using UWP and have some special functions for dealing with them, although they also use some of the standard built-in functions for leaderboards. The 2017 Xbox Live stats system simplifies the whole procedure for making achievements and leaderboards, permitting you to create and use the different systems from within GameMaker Studio 2 . The main difference between the 2017 system and previous systems is that you no longer have to define all of the stats you use in game on XDP, and you do not need to tie achievement unlocking to a stat event/rule either (as they are unlocked by a direct function call instead).

NOTE: Although there is no manifest file required with this system, you can still set up some stats on XDP/MDC. Ones setup there will be considered featured stats which means you can have global leaderboards and the stats turn up on the games dashboard page. For more information, please see the MS article Configuring Featured Stats or Leaderboards on Universal Dev Center with Data Platform 2017.

Before calling any of the stats functions listed below, you must make sure that the user is logged in (see the User functions listed above) then setup the stats system and add the user to it using these functions:

• xboxlive_stats_setup
  
• xboxlive_stats_add_user

The rest of the 2017 stat functions are as follows:

• xboxlive_stats_remove_user
  
• xboxlive_stats_flush_user
  
• xboxlive_stats_set_stat_real
  
• xboxlive_stats_set_stat_int
  
• xboxlive_stats_set_stat_string
  
• xboxlive_stats_delete_stat
  
• xboxlive_stats_get_stat_names
  
• xboxlive_stats_get_stat
  
• xboxlive_stats_get_leaderboard
  
• xboxlive_stats_get_social_leaderboard
  
• xboxlive_achievements_set_progress
  
• xboxlive_get_stats_for_user
  
• xboxlive_read_player_leaderboard
  
• xboxlive_fire_event
  

Match Making

Matchmaking (multiplayer) for Xbox Live and UWP requires a bit of configuration, partly via a configuration file which defines what network connections you are going to use, and partly via setup of session templates and matchmaking hoppers on the Xbox Developer Portal. GameMaker Studio 2 supports this through the use of the UWP target and permits you to do the following:

• Create a multiplayer session
• 
  
• Find (and/or join) a multiplayer session
• 
  
• Be notified when relevant players join or leave a session, as well as receive their network connection details
• 
  
• Be notified when the session host migrates to a different user
• 
  
• Get a list of users in the session
• 
  
• Leave a session
• 
  

Xbox Live network connectivity relies on something called a Secure Device Association, which is basically a contract defining exactly how the device connects to other devices and what sort of data it is able to communicate using that connection. These are configured using a file which you need to include in your project. You can find an example of this file here. The main important points in the file are the protocol and port numbers for each socket description, as these must match what you actually set up in code.

Once you have created this network manifest file, it should be added to the project as an included file. Then, inside the UWP Game Options, in the Xbox One General tab, it should be selected in the "Included File for Network Config Manifest" combo box.

To create a multiplayer session, you need to specify what Session Template is going to be used. These session templates are defined on the XDP, but an example is shown below:

Session Name: MatchSession
Contract Version: 107
Session Template (JSON text):
    {
    "constants": {
        "system": {
            "version": 1,
            "maxMembersCount": 12,
            "capabilities": {
            },
            "memberInitialization": {
                "externalEvaluation": false,
                "membersNeededToStart": 1
                }
            },
        "custom": {}
        }
    }

A description of the fields can be found in "Session Overview" in the XDK help file. Note that we currently don't support setting session parameters dynamically from GameMaker Studio 2.

Along with the session template, a matchmaking hopper must also be set up to allow the session to be found (this is also done on the XDP). Hoppers are used to define rules which are used when matching players. As with session parameters, we don't currently support setting hopper parameters dynamically from GameMaker: Studio. See the "SmartMatch Matchmaking Configuration" section in the XDK help file for further details.

The following functions are available for XboxLive matchmaking (note that you will also need to use the GameMaker Studio 2 Networking Functions for the connections etc...):

• xboxlive_matchmaking_start
  
• xboxlive_matchmaking_stop
  
• xboxlive_matchmaking_create
  
• xboxlive_matchmaking_find
  
• xboxlive_matchmaking_session_get_users
  
• xboxlive_matchmaking_join_session
  
• xboxlive_matchmaking_session_leave
  

GameMaker Studio 2 provides an extra set of matchmaking functions for you to use to invite other players on the network to join a session, or for you to accept an invitation to join someone else's session. The functions available are:

• xboxlive_matchmaking_send_invites
  
• xboxlive_matchmaking_set_joinable_session
  
• xboxlive_matchmaking_join_invite
  

When the player accepts an invitation from another player, one of two things happens:

• 1) If your game is currently running, you will receive a Social Asynchronous Event with async_load DS map containing the following keys/values:
  
  
  • "id" - This will be set to MATCHMAKING_INVITATION.
  • "invitation_id" - This is the unique session ID value
  • "invitation_host" - This is the unique session ID value for the session host
  You should save the ID and Host values then leave any sessions you need to, and call the function xboxlive_matchmaking_join_invite(), passing in as arguments the invitation ID and invitation host values in a Step event.
• 
  
• 2) If your game is not currently running, it will be started by the OS. You will receive the same type of Social Asynchronous Event with the same keys set as those listed above. Save them to variables, then connect to Xbox Live matchmaking and finally call xboxlive_matchmaking_join_invite().

Once you have called xboxlive_matchmaking_join_invite() the user will attempt to join the session and you will receive Asynchronous Social Events as if you had called xboxlive_matchmaking_find() on this session.